Chapter 3. OPERATORS AND EXPRESSIONS PILOT accepts expressions in many contexts. An expression is a combination of variables, numeric constants, string constants, functions and operators. Expressions are formed in the normal manner allowed by other programming languages. Operator precedence is similar to that of basic. Parentheses may be used to group subexpressions. EXAMPLE: simple expressions X + 5 SIN(I) 2.5 (A + B) <= (C + D) DATA TYPES Each element of an expression is a number or a string value. Numbers are stored in floating point form with an accuracy of about 6 decimal digits. Strings are stored in variable length form with a terminating null character. Each operator or function expects to act on a particular type of argument, and in return produces a particular type of result. For example, + expects two numeric arguments and it produces a numeric result. A unique and convenient feature of PILOT is auto-type conversion. This means that any time an argument is of the wrong type (string or number) it is automatically converted to the correct type for the context. A number is converted to a string in a manner like that of the STR function, which puts the value in printable format with decimal places only if necessary. A string is converted to a number in a manner like that of the FLO function, which scans the string for the first number value or returns zero if no number is found. VARIABLES A variable name can be up to length six. The first character must be a letter. Other characters may be letters or digits. The last character may be a $ to signify a string variable. Upper and lower case letters are considered to be equal when naming a variable (i.e. - XYZ and xyz name the same variable). A string variable must be dimensioned in a D: statement before it can be used to store a string value. EXAMPLE: variables X COUNT J5 able NAME$ SYSTEM VARIABLES There are several system variables which can be used in the same context as other variables. %A - answer counter %A is a numeric variable equal to the number of times the last A: has executed without any other intervening A:. It tells how many attempts the student has made on this question. %B - answer buffer %B is a string variable which is set to the response given by the student on each A:. %B has a maximum length of 80 characters. It can be subscripted like any string variable. %E - return point of last U: %E is a numeric variable which returns the jump value of the return point of the most recent USE statement. It is the location which would be returned to via an END statement. %N %M %L - match result variables These are parsing variables which return information about the last MATCH. See the MATCH statement for more details. See also: COMPUTE, DIMENSION, SUBSCRIPTING SUBSCRIPTING array (position) strng$ (position) strng$ (position, length) SUBSCRIPTS are used to select an individual value out of a numeric array or a substring out of a string variable. Subscripts consist of a position and possibly a length, enclosed in parentheses after a variable name. The position and length values can be expressions. Before subscripts can be used the variable must have been dimensioned. See the DIMENSION statement for more information. NUMERIC ARRAY SUBSCRIPTING Numeric arrays start at subscript zero and end at the dimensioned size. An attempt to subscript beyond the array limit results in an error message. A reference to an array name without subscripts results in a reference to item number zero of the array. EXAMPLE 1: array subscripts C: A(3) = X C: A(I) = A(I) + 1 C: LIST(J) = A * 5 STRING SUBSCRIPTING String subscripts start at one. If you specify a starting position less than one, PILOT will assume you meant one. If you omit the length, a length of one is assumed. The portion of a string picked out by subscripts is sometimes called a substring. EXAMPLE 2: simple string subscripts D: X$(20), Y$(10) C: X$ = "ABCDEFGHIJKLMNOP" C: Y$ = X$(3) Y$ is now equal to "C" C: Y$ = X$(5,4) Y$ is now equal to "EFGH" You can assign a value into a substring by placing the subscripted string variable on the left hand side of a COMPUTE statement. In this case, only the characters within the substring are modified. All other characters within the string are unchanged. EXAMPLE 3: assignment to a substring D: X$(20) C: X$ = "ABCDEFGH" C: X$(3) = "s" X$ is now equal to "ABsDEFGH" C: X$(4,3) = "12345" X$ is now equal to "ABs123GH" C: X$(4,3) = "xy" X$ is now equal to "ABsxy GH" Since a string variable can contain a variable number of characters at any one time, it is possible that its current length is less than its maximum length as set up by the DIMENSION statement. If, when a subscripted string is not the target of a COMPUTE statement, the start subscript is over the end of the current string length, the returned value is a null string. If the start subscript is within the string but the length would run over the string length then only the remaining characters are returned. EXAMPLE 4: padding a string to its max length D: X$(100) C: X$(100) = " " X$ is now equal to 100 spaces You can access a substring of any length you wish. If you leave off the length, then the substring is assumed to be length 1. If you give a length that would go past the current end of the string, then the substring goes from the starting position you specified to the current end of the string. So by using a large length value you can reference a substring starting at a given position and containing the rest of the string. This is similar to the RIGHT function in some languages. EXAMPLE 5: the rest of the string C: X$ = "ABCDEFGHIJ" C: Y$ = X$(3,20) Y$ is now equal to "CDEFGHIJ" See also: DIMENSION, VARIABLES NUMERIC CONSTANTS [-]digits [-]digits.digits A numeric constant consists of an optional leading minus sign, a string of decimal digits optionally including a decimal point. Numbers are retained to about six digits of accuracy. EXAMPLE: numeric constants 5 63.789 -42.1 STRING CONSTANTS "text" A string constant, or literal, consists of zero or more characters enclosed in quotes. EXAMPLE: A$="BANANA" T(X$ < "A"): NO SIR. OPERATORS ARITHMETIC x + y x - y x * y x / y x % y (remainder of x/y) -x To compute A to the B power use EXP(B*LNE(A)) RELATIONAL x < y x > y x = y x <> y x <= y x >= y Comparison is numeric if x is a number or string if x is a string. For string comparisons the shorter string is padded on the right with spaces for comparison purposes. Relational operators always yield a one for true or a zero for false. LOGICAL x & y (true if both x and y are non-zero) x ! y (true if either x or y is non-zero) ^x or ~x (true if x is zero) Logical operators always produce a 1 for true or a zero for false. STRING x$ !! y$ (concatenation) Concatenation produces a string consisting of the string value of y$ appended to the right end of the string value of x$. FUNCTIONS A built-in function can be used in an expression to return a pre-defined computation or value. The function name is always followed by parentheses containing one or more function arguments. The function arguments may be expressions. ABS(X) - the positive value of X ABS(9) is 9, ABS(-9) is 9 ASC(X$) - the numeric value 0-255 of char X$, ASC("A")=65 ATN(X) - arctangent in degrees of X, ATN(1) is 45 AUX(0) - reads the com1: (rs232) port Returns CHR(0) if no byte ready to read, or a character from CHR(1) to CHR(255).The com1: port must be set up via a DOS MODE command before entering PILOT. CAP(X$) - the upper case value of string X$ CAP("X2 is it.") is "X2 IS IT". COS(X) - cosine of X degrees, COS(60) is .5 CHR(X) - the Xth ascii character, CHR(65) is A CLK(n) - time and date clock n=0 gives the time of day in seconds, n=1 gives year; n=2 gives month; n=3 gives day DEC(X,n) - string value of number X with n decimal places DEC(13.45095,2) is 13.45 EXP(X) - e to the X power, EXP(3.5) is 33.11 ... FIZ(X$) - size of a file X$ MUST BE a string variable, NOT an expression. The variable contains a path or file name. The return value is the length, in bytes, of the file, or -1 if the file does not exist. FLO(X$) - convert a string to a real number The numeric value of the first number found in string X$, FLO("Either 12 or 14") is 12. INS(X$) - search for a character in %b Returns zero if character X$ is not in %B, otherwise the first position in %B where X$ is found. INP(X) - machine level IN instruction Returns a byte from io port X. INT(X) - value of X truncated to an integer, INT(13.89) is 13 KEY(X) - return keyboard status Returns zero if no key is pressed, otherwise the ascii code for the depressed key. If X=0, then the character is read from the type-ahead buffer. If X=1, then the character is left in the type ahead buffer. LEN(X$) - current length of string X$, LEN("abc") is 3 LNE(X) - natural log (base e) of X, LNE(10) is 2.302 ... LOG(X) - log base 10 of X, LOG(10) is 1.00 MEM(0) - number of unused bytes for strings and arrays MOD(0) - returns the current screen mode OFF(X$) - memory offset address Returns the offset part of the address of the string variable. PEK(X) - read memory byte Returns a value from 0 to 255 equal to the byte in memory at offset X in the segment whose base is in the variable %A. RND(X) - random number generator If X is zero, returns a random fraction from 0 to 1. If X>0, returns a random integer from 0 to X-1. If X=-1, a fixed sequence of random numbers is used for all subsequent uses of RND and SFL. RSP(X$) - the string value of X$ with all spaces removed, RSP("That is all") is "Thatisall". SEG(X$) - memory segment address Returns the segment part of the address of the string variable. SFL(X$) - shuffled version of the characters in string X$, SFL("abcde") might be "bcade". SGN(X) - -1 if X is negative, 0 if X is 0, +1 if X is positive SIN(X) - sine of X degrees, SIN(30) is .5 SPC(n) - gives n spaces SQR(X) - square root of X, SQR(9) is 3 STR(X) - the string value of number X SWP("xy") - swap characters Returns a string equal to the value of %B except that each character x is changed to character y; if %B holds "Why not exit?", SWP("xy") is Why not eyit? TIM(0) - response time in seconds of last A: TSP(X$) - string value of X$ with trailing spaces removed WRD(X$,n) - gives the nth word in the string X$ WRD("one two three four",2) returns "two" XCR(0) - x position of the text cursor XPX(0) - x position of the graphic turtle YCR(0) - y position of the text cursor YPX(0) - y position of the graphic turtle EXAMPLE 1: use AUX to read N characters from serial port D:X$(80) C:X$ = "" C:N=10 *LOOP C:X$= X$ !! AUX(0) J(LEN(X$)10):DONE X: "J:QUES" !! X$(N) . . . *QUESA . . . . . . J:LOOP Chapter 4. GOTO AND ESCAPE COMMANDS GOTO COMMAND The GOTO command can be enabled or disabled by an option on the PROBLEM statement. If enabled, then each ACCEPT statement automatically checks the student response for the command: GOTO destination If present, a JUMP to the destination is immediately performed. The destination can be any of those available on the JUMP statement. This feature is extremely useful when writing or debugging a long program. You can enable the GOTO option, then when testing, you can jump around in the program to test the relevant section. Once the program is debugged, you can disable the GOTO command. You could conceivably allow the student to use GOTO to navigate within a program, however, there is a better way to give the student the branching control needed. ESCAPE COMMAND The ESCAPE command can be enabled or disabled by two options on the PROBLEM statement, the E option enables the ESCAPE key, and the F option enables the FUNCTION and CURSOR keys. You can choose to have either, both or neither option enabled. The enabled keys become "HOT KEYS" that cause an immediate action to take place if the student presses the key while responding to an ACCEPT. If one of the (enabled) hot keys is detected the automatic action is equivalent to: U: SYSX That is, the subroutine named *SYSX is called. It is up to you to insure that the label *SYSX is present in the program module and that it contains the code to perform the desired special action. The SYSX routine can be used to record comments from the student as shown in the first example below. It can also be used to allow the display of a menu or glossary on demand. The SYSX routine should end with an END statement. If no argument is given on the END then a return is made to the statement after the ACCEPT. The first example below returns to re-execute the ACCEPT. Note also that since the END can specify a label, it is not necessary to return at all, as shown in the second example. EXAMPLE 1: SYSX used to record student comments. If the student enters a comment, then the ESCAPE key, the comment is written to the KEEP file. *SYSX K:%B E:@A EXAMPLE 2: SYSX used to return to a main menu *SYSX T: GOING TO MAIN MENU. E:MENU EXAMPLE 3: SYSX used to display a help page, then return to allow the student to answer again. *SYSX GSX: (save screen image) U:HELP (go display the help) T:Push a key to go on. W:30000 (pause while he reads) GX: (put the screen back) E:@A (return to ACCEPT) ANSWER BUFFER DURING AN ESCAPE When the SYSX routine is reached, the last character in the answer buffer, %B, is the character that caused the escape function to take place. If the student had entered any data prior to pushing the hot key, then that data is also in %B, as usual. This example shows how to separate the last character from %B. EXAMPLE 4: SYSX used detect which hot key used *SYSX C: L = LEN(%B) (length of %B) C: K = ASC(%B(L)) (K is hot key value) C(L>1): %B = %B(1,L-1) (remove last char) CHANGING THE ESCAPE KEYS The P:E option enables the ESC key. It generates ASCII code 27. If you wish to use another key for this purpose use the NX: statement to change which key generates code 27. Similarly, P:F enables codes 187 through 221. These are the codes normally generated by the function keys, the shifted function keys, and the keys in the cursor control pad area. You could re-assign various keys in and out of this range to control which keys are hot keys. COMPATIBILITY For compatibility with other versions of PILOT. The P:E option also enables the escape to *SYSX if the first character of a student reply is the "@" character. This check takes place only after the student has pushed the ENTER key to end the response. See also: PROBLEM, ACCEPT, USE, END Chapter 5. ERROR MESSAGES PILOT is programming-error tolerant. If an error is detected, the statement in error is displayed. Before it is a message which identifies the problem. Execution then pauses. The user can push ctrl-c to stop the program or push any other key to ignore the error and continue execution with the next statement. If it is at all possible to go on, and it usually is, PILOT will continue with the program. The following error codes are used by PILOT. Error messages can be suppressed by setting the I option on the PROBLEM statement. disk - i/o error in program file This usually means that the diskette has unreadable data on it. exp - invalid or missing expression This error can signify any number of syntax errors in the construction of a PILOT statement. Usually it means that you have used operators or functions improperly. file - no file open or disk i/o error This error can mean that a diskette is write-protected, full, or the directory is full. It can also mean that the FILES=n parameter in your CONFIG.SYS file specifies too few files for your system. Try placing FILES=16 in your file CONFIG.SYS. label - missing destination A syntax error in specifying a jump label. link - program file not found (program stops) You linked to a file or path name that could not be found. lspace - too many labels in one program module One program module can contain 200 labels. Break the module into several smaller ones. mode - graphics done when not in mode 4, 5 or 6. The hardware will not do graphics in a text mode. open - can not open disk file Disk drive not ready, write protected, or full. See also "file" above opcode - invalid op code or modifiers PILOT does not recognize what comes before the colon as a legal statement. paren - missing parenthesis quote - missing closing quote sprite - illegal sprite syntax Attempt to use a string less than 2218 bytes as a sprite table, or invalid sprite usage. sspace - memory overflow Not enough string and array space left to do string operations. subscript - too big for the array syntax - statement has bad command or operator uspace - use call level is too deep ( over 32 ) var - missing variable name vspace - over 200 variables in use xspace - no more memory for arrays or strings Chapter 6. DISTRIBUTING PROGRAMS If you develop a program using PILOT and wish to provide that program to others who may not have PILOT, you can do so by following these procedures. First, develop and test your program in the normal way. Next, use the PCRYPT program to translate your lesson files into a binary format which is not human-readable. To do this type PCRYPT name n n is a number which represents the maximum program length in 8KB increments. If n is omitted, PCRYPT defaults to a value of 4 (32 KB). This command reads your program from file name.PIL and produces a file named name.PIX. It is impossible to go backwards from a PIX file to a PIL file, so be sure to keep the original. If your lesson uses LINK statements you must use PCRYPT to translate all applicable lesson files. The following command can be used to encrypt all PIL files in the current disk or directory: PCRYPT * n To run the encrypted (.PIX) version of a program use: CPI name n To distribute your program provide the PIX files and the file CPI.EXE to the user. The user can run the program but can neither read nor modify your source code. Do not duplicate or distribute copies of any other files provided with the PILOT system. Chapter 7. EZ EDITOR EZ is a full screen text editor. You can use it to create and edit your PILOT programs. To use it enter: EZ name.PIL where name.PIL is the file name you wish to create or modify. If the file does not exist, it is created. If it does exist, it is read into memory and displayed on the screen. When you finish with EZ, a backup copy of the file is retained as name.BAK. You always have two copies of your program file: name.PIL is the current copy and name.BAK is the file just prior to the last time you edited the file. The EZ command and file name may be preceded by optional drive or path designations per normal DOS conventions. The maximum size text file supported by EZ is 50,000 bytes. EZ FUNCTION KEYS Once in EZ, the screen is a window on the text file. The various cursor and function keys are used to move around in the text and to add, change or delete text. When adding or replacing text, you just type on the keyboard; what you see on the screen is what you get in the text file. The following summary shows the various keyboard functions you can use. The F9 key may be used at any time to display an on-line help menu which summarizes these functions. Arrows - move the cursor one space in any direction TAB - skip to next tab stop. Tab stops are each 10 columns HOME - move to the first text line of the file END - move to the last text line of the file PG UP - move up (backwards) one screen PG DN - move down (forward) one screen INS - insert a space into the line DEL - remove the current character F1 - insert line When in column 1: Insert a blank line. When not in column 1: Split line into two lines. F2 - delete line When in column 1: Remove the current line and place it on the PICK STACK. When at end of a line: join the next line to the current line. F3 - copy the current line onto the PICK STACK F4 - insert top line off the PICK STACK before current line F5 - search string, or goto a line number, see below shift F5 - replace search string, see below F6 - shift to extended character set for next key pressed shift F6 - shift lock to extended character set Shift until F6 pushed again or the ENTER key is pushed. This enables the insertion of characters from 128-255 into a program file. See appendix B for available characters. F7 - expand a MACRO into the text shift F7 - insert a file into the text Enter the name of a file to be copied into the current file and inserted prior to the current line. F8 - switches to/from graphics mode In graphics mode characters defined by N: statements in this program file are displayed. User can enter name of another PILOT file which has further N: statements to be executed. shift F8 - enter character editor (only in graphics mode) F9 - on-line HELP key shift F9 - write or print all or part of text Write all or a part of the text to a disk file or to the printer. To send the text to the system printer enter PRN: as the file name. To start the write at a line other than the first line of the file, place a line containing only [[[[ prior to the first line to be written. To stop writing prior to the end of the file place a line containing only ]]]] after the last line to be written. F10 - save file and exit to DOS shift-F10 - abandon edited file, exit to DOS without saving USING THE PICK STACK IN EZ The PICK STACK is an invisible last-in/first-out buffer which can store up to 16 lines of text at a time. It has three uses. First, if you accidentally delete some lines using F2, they can be put back again by pushing F4. Second, to move lines push F2 once per line to delete them, then move to the desired location and push F4 once per line to re-insert them in the new place. Third, to duplicate lines push F3 once per line to copy them onto the PICK STACK, then move to the new location and push F4 once per line to insert them in the new place. SEARCH AND REPLACE To search for a line number push F5 then press the "@" key, the line number, and ENTER. To search for a string push F5 then type the string and push ENTER. To find the same string again just push F5 then ENTER, you do not need to type the search string again if it is the same as the last search. To search for a string and replace it with another string: push F5, then type the search string (but don't push ENTER yet). Next push shift-F5, then type the replacement string and push ENTER. EZ will find and display the next occurrence of the search string. At that time push shift-F5 to replace the string, or just push F5 to find the next occurrence. By using F5 and shift-F5 alternately you can see each occurrence of the search string to decide whether it should be replaced. To find each successive occurrence of the search string and immediately replace it with the replacement string, just push shift-F5. repeatedly, once for each time you wish to search and replace. MACROS IN EZ The F7 key is used to read and expand a macro into the text. A macro is a pre-programmed sequence of instructions which can be accessed as a whole to reduce your programming time. To include a macro push F7 then type the name of the macro file and push ENTER. The macro may prompt for information on the bottom two lines of the screen prior to completing the macro expansion. More information on macros can be found below. See "How to Write a Macro for EZ". EXTENDED CHARACTERS IN EZ The extended characters, from ASCII 128 to 255, do not have keys on the keyboard. By using the F6 key you can enter these extended characters. To enter one, push F6, then another key. A value of 128 is added to the normal value of the key, which produces a character in the extended range. Appendix A contains a list of the numeric values for the various keyboard combinations. The character editor, described below, can also be used to determine the key combination for any particular extended character. When EZ is entered, the screen is in text mode. In this mode you see the text mode extended characters for codes 128 to 255. These are the characters built-in to the hardware which would appear in a PILOT program for text modes (0-3). The F8 key switches EZ to graphics mode. In this mode you see the user- defined characters for codes 128 to 255. The PILOT N: statement allows you to redefine character patterns to be displayed when the PILOT program in executed. The F8 key allows you to see the re-defined characters while editing your program with EZ. When F8 is pushed, all N: statements in the file are executed, just as they will be executed when the PILOT program is run. Also, you are prompted for the name of another file which contains N: statements you wish to execute. This allows you to see re-defined characters even if the character definitions are in a file other than the one in which you are editing. When entering the file name, you must enter the entire name (eg. PART7.PIL). If you do not wish to enter another file name, just push ENTER. CHARACTER EDITOR To simplify the task of creating your own special characters EZ contains the Character Editor. Special characters should not be confused with character "fonts". Special characters are limited to the standard 8 by 8 pixel character grid. Character fonts are used to display characters of smaller or larger proportions. Creation of fonts is documented in the section entitled "Font Editor". To enter the character editor hold SHIFT and push F8. The character editor is available only after you have used the F8 key to switch EZ from text to graphics mode. With the character editor you can: 1) See the 128 character patterns which makes up the extended character set. 2) Look up the key combination needed to enter any particular extended character into your program file. 3) Modify one or more extended character patterns. 4) Create new extended characters. In PILOT you re-define a character grid by specifying 64 dots and slash characters on a NEW CHARACTER statement. The character editor lets you see the character grid in a normal size and in a blown-up size, so that you can see and change each dot individually. When you are done editing a character with the character editor, the character editor creates the appropriate NEW CHARACTER statement and inserts it into your program text for you. Once you enter the character editor, the on-screen help menus provide all the information you need in order to use it effectively. CHARACTER EDITOR MODES The character editor has two operating modes: GRID MODE and SELECT MODE. In GRID MODE you can edit the dot pattern for a selected character. In SELECT MODE you can pick out which character you wish to work on. To enter the character editor in GRID MODE, push the SHIFT-F8 when the cursor is on an N: statement. The character represented on the N: statement is automatically selected for editing. To enter the character editor in SELECT mode push the SHIFT-F8 when the cursor is not on an N: statement. In either mode you see the entire 128 characters displayed in the upper right part of the screen. The characters are displayed as they are currently defined by the N: statements in the current file and those in any extra file you named when you pushed F8 to enter graphics mode. To the left you see the currently selected character in a blown-up form and in normal size displayed in colors 1, 2 and 3. Also shown is the key combination you use after F6 to enter this character into your text file and the numeric value of the character, from 128 to 255. If you are using extended characters the SELECT MODE is an easy way to look up the keys you should press to enter any extended character into your text. To do this push SHIFT-F8, position the cursor to the desired character, note the F6 key combination shown, then push F10 to go back to text editing mode. SELECT MODE In SELECT MODE you can use the arrow keys to select the desired character. Then push F9, to go to GRID MODE, to edit the character or push F10 to return to text editing mode. In SELECT MODE you can copy one character pattern to another as follows: First move to the character to be copied, push F3 to pick up the character, then move to the destination character and push F4 to copy it. Notice that to the left of the character table is the character you have currently picked up. GRID MODE In GRID MODE you use the arrow keys to move the cursor around within the blown-up character cell. You can use the various function keys to modify the character pattern as you wish. Note that the starting grid is saved in the "picked up" character spot. If you accidentally destroy the character grid as you edit, you can put it back by pushing F4. You can pick up the current grid at any time by pushing F3 again. Once you have finished with the character, you can push either F9 or F10. In either case, the character editor changes or inserts the appropriate N: statement in your text file. If you push F9, then you are moved to SELECT MODE to select another character for editing. If you push F10 you are returned to text edit mode. GRID MODE FUNCTION KEYS Arrows - move cursor 1 space in any direction (if stream mode is on, then set or clear the dot) F1 - turn dot on and turn off stream modes F2 - turn dot off and turn off stream modes shift F1 - toggle stream set mode shift F2 - toggle stream clear mode F3 - pick up grid and save it F4 - restore grid to last picked up value F5 - invert all dots in the grid shift F5 - clear grid (turn all dots off) F6 - rotate grid clockwise 90 degrees shift F6 - reflect grid across a vertical center F7 - roll grid one bit to the left F8 - roll grid one bit up F9 - save N: statement and goto SELECT mode F10 - save N: statement and goto text editor HOW TO WRITE A MACRO FOR EZ The user of EZ can call upon pre-made code sequences which are included in the user program by use of the F7 function key. A pre-made code sequence is called a MACRO and is stored as a text file. By convention, PILOT language macros are named with a file suffix of ".PIM". Usually a macro is used to include the code in a program to perform some well-defined task. Such a task might be to display a menu, ask a multiple choice question, or update a student score record. The program author can save much time by using a macro rather than taking the time to write a commonly used code sequence over and over. Often the macro has been written ahead of time by another party, but the author might create personally useful macros also. The following code could be stored in a file ANIMATE.PIM and used to move the word "Hello" across the screen. TS:G10,10 TS:*20(A Hello;D3;Wr) To use it the author would push F7, type the name ANIMATE.PIM, and the above two lines would be copied into the current program file. SYMBOLIC PARAMETERS IN A MACRO Very often the desired code sequence needs to be expanded in slightly different ways depending on the exact needs of the program. For this reason a macro can be written such that symbolic parameters can be filled in by the user each time the macro is expanded. For example, assume that the above macro should permit the author to determine what word is moved across the screen. The file ANIMATE.PIM could be modified as follows: TS:G10,10 TS:*20(A ?a;D3;Wr) Now, when the author calls upon the macro, EZ prompts the author for the value to be substituted in where the symbolic parameter "?a" is found. If the author replies "happy", then the code that is expanded into the author's text is: TS:G10,10 TS:*20(A happy;D3;Wr) The same technique could be used for the starting position, number of steps to take and delay time: TS:G?a,?b TS:*?c(A ?d;D?e;Wr) Now when the author calls upon the macro, EZ prompts for five symbolic parameters: ?a, ?b, ?c, ?d and ?e. One macro can use up to 20 different symbolic parameters, named ?a through ?u. Upper and lower case letters can be used and are considered equal. When expanding the macro into the text, EZ prompts for the string to be substituted for each symbolic parameter on the first occurrence of the parameter. Then the string is substituted for all occurrences of the symbolic parameter within the macro. ?SET COMMAND A macro can also set the value of a symbolic parameter directly by inclusion of a ?SET command line. The ?SET command line is not ever present in the resultant expanded text. The function of the ?SET command is only to set the value of a symbolic parameter. The format of the ?SET command is as follows: ?SET a=value "a" represents one of the symbolic parameters,"a" through "u". The value string is assigned to the symbolic parameters. LABEL SYMBOLIC PARAMETER There is one special symbolic parameter, signified by four question marks, as shown in this example: *A???? T:#N C:N=N+1 J(N<10):A???? EZ substitutes a unique four digit number for the ????. It is unique in that prior to expanding the macro, that number is not present anywhere in the text. Once the four digit number is selected, it is substituted for each occurrence of the ???? in this expansion of the macro. If the same macro is expanded again, then a new four-digit number is used. In this way a macro can contain labels which are guaranteed to be unique for each occurrence of the macro. ?REM COMMAND It is possible to insert remarks or instructions to the user within a macro using the "?REM" command. For example: TS:G10,10 ?REM Enter the word to animate. TS:*20(A ?a;D2;WR) In the above case, the user would see the message "Enter the word to animate." just prior to the prompt for the symbolic parameter "?a". This could be used to inform the user of the macro as to the expected values to be filled in. The ?REM line is not included in the macro output. CONDITIONAL MACRO EXPANSION There are several macro commands which can be inserted in a macro to control how it is expanded. It is possible to conditionally include or skip sections of code via the setting of the "expand flag". When the expand flag is on then text lines are included in the result, when the expand flag is off then text lines are skipped. The macro commands which can affect the setting of the expand flag are shown below. Each command must start at the beginning of a line. The keyword may be upper or lower case. The command line itself is not placed in the resultant expanded code. The conditional macro statements are show below. ?ON turn on the expand flag ?OFF turn off the expand flag ?ELSE invert the setting of the expand flag ?ASK question text The question text is presented to the user. If the user responds by pushing the "Y" key then the expand flag is turned on. Otherwise it is turned off. ?IF a=value "a" represents one of the symbolic parameters, "a" through "u". If the symbolic parameter matches the value string, then the expand flag is turned on. Otherwise it is turned off.